Safe c interop #1071
Safe c interop #1071
Conversation
hnrklssn
requested review from
timsneath,
tkremenek,
shahmishal and
davelester
as code owners
|
Have you considered putting this documentation in a docc catalog? |
I have not! I can't speak for Gábor and Egor, but I simply kept writing in the established file. What are the benefits of a docc catalog? I haven't contributed to the website before, so I don't really know how things work |
| These overloads provide the same bounds safety as their `UnsafeBufferPointer` equvalents, but with | ||
| added lifetime safety. If lifetime information is available the generated safe overload will always | ||
| choose to use `Span` - no `UnsafeBufferPointer` overload will be generated in this case. This means | ||
| that existing callers are not affected by annotating an API with `__counted_by`, but callers using the |
There was a problem hiding this comment.
Is there upstream documentation for these annotations in Clang? Do we want to link to that?
There was a problem hiding this comment.
There are upstream docs for __counted_by, but they are outdated, since only a limited set of use cases are currently supported in upstream. The upstream docs currently only list support for flexible array members, which we don't import to Swift in the first place.
There was a problem hiding this comment.
You can refer to this documentation https://clang.llvm.org/docs/BoundsSafety.html
|
I remember the title was "Safe C++ and Swift interop" or something like that. If so we would also need to update it to include "C" as well. |
| source compatiblity, nor does it affect ABI. Instead it leverages bounds attributes to express the | ||
| pointer bounds in terms of other parameters in the function signature. | ||
|
|
||
| #### Annotating Pointers with Bounds Attributes |
There was a problem hiding this comment.
This elaborates "UnsafeBufferPointer" in a great length, which is not the most recommended usage. I'd elaborate all these with "Span". Since lifetime annotations are already introduced for C++ span, you can just mention that it's still necessary without still focusing on the bounds annotations.
And then "UnsafeBufferPointer" can be briefly mentioned afterwards like -- if lifetime annotations are missing, it's imported as "UnsafeBufferPointer" instead of "Span".
This adds documentation around __counted_by, __sized_by, API notes, and using lifetime attributes in C.
|
I'm having a bit of trouble deciding how to format the comparison between C and Swift; the narrow page size makes it hard to fit side-by-side comparisons. Following the approach used elsewhere on the page looks like this: 
Using HTML tables we can get tables with code blocks. This gives us syntax highlighting, but unformatted it requires a fair bit of horizontal scrolling.
With some formatting the situation improves, but they still don't fit without horizontal scrolling.
We could instead skip the table and just use two separate code blocks before/after each other. Following the code formatting of the previous code blocks the C code looks like this, which works I guess, but doesn't look great right after each other imo.
|
This adds documentation around __counted_by, __sized_by, API notes, and using lifetime attributes in C.
This is stacked on top of #980.